Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 001 / piblist.arc / PIBLIST.DOC < prev next >

Wrap

Text File | 1985-03-28 | 31.3 KB | 398 lines

(*---------------------------------------------------------------------------*) (* *) (* PIBLIST - A utility program for displaying text files on PC screens. *) (* *) (* Introduction *) (* ------------ *) (* *) (* PIBLIST is a general-purpose utility program for displaying *) (* sequential ascii text files to the PC's screen. *) (* *) (* PIBLIST displays one screenful (or "window") of text at a time. *) (* A prompt called the "paging prompt" is displayed at the bottom *) (* of each screen. Commands are provided to position the viewing *) (* window both vertically and horizontally within the file. *) (* Commands can be specified in either absolute or relative format, *) (* and in terms of lines, screens, pages, or columns. *) (* *) (* *) (* Executing PIBLIST from DOS: *) (* --------- ------- ---- --- *) (* *) (* PIBLIST fname /FF /LPC /T /H *) (* *) (* fname --- the ascii file name to be listed in the form: *) (* driveletter:\path\filename.ext *) (* where *) (* driveletter = the drive on which the file resides *) (* ( optional ) *) (* \path\ = a subdirectory path ( optional ) *) (* filename.ext = the actual file name. *) (* *) (* Examples: *) (* *) (* c:\mydir\afile.doc *) (* \mydir\another.mem *) (* myfile.dat *) (* *) (* If the file name does not appear, PIBLIST prompts for *) (* it. *) (* *) (* /FF --- The file is divided into pages by form feed characters *) (* appearing in column one of the first line on a new *) (* page. The form feed is ascii character 12. *) (* /LPC --- The file is divided into pages by character ones *) (* appearing in column one of the first line on a new *) (* page. Such files are commonly created by FORTRAN *) (* programs or files prepared for line printers on minis *) (* and mainframes. *) (* *) (* Note: /FF and /LPC are mutually exclusive. If both are given, *) (* the one which appears last is used. If neither appears, *) (* the file is assumed to not be divided into pages. *) (* *) (* /T --- requests that tabs be expanded to sequences of blanks *) (* when displayed ( optional ) *) (* *) (* /H --- requests that the high-order bit of each character *) (* be stripped before the character is displayed. *) (* ( optional ) *) (* This allows WordStar files to be displayed. *) (* Note that this mode slows down PibList considerably, *) (* so you shouldn't ask for bit-stripping unless you *) (* need it. *) (* *) (* *) (* The paging prompt *) (* --- ------ ------ *) (* *) (* The following prompt is displayed at the bottom of each screen: *) (* *) (* [Pa Sb Lc Cd We] ( Enter ? for help) ? *) (* *) (* The numbers a, b, c, d, and e specify the current page *) (* number, screen number, line number, column number, and *) (* width setting respectively. The page, screen, and line *) (* numbers refer to the bottom (last) line in the currently *) (* displayed window. The column number is the number of the *) (* leftmost column displayed in the window, where columns are *) (* numbered 1, 2, 3, and so on. The width is the number of *) (* columns displayed for each line in the window. *) (* *) (* Commands *) (* -------- *) (* *) (* The commands described below can all be typed in response to any *) (* paging prompt. All of the commands are single letters, but may be *) (* preceded or followed by direction indicator (+.-) and counts. *) (* In all cases the letter commands must be terminated by a carriage *) (* return. Leading and trailing blanks are ignored. Embedded blanks *) (* are ignored except inside numbers. Letters may be typed in upper *) (* case, lower case, or any mixture of upper and lower case. A lower *) (* case "n" below denotes any unsigned decimal integer. *) (* *) (* For convenience, the commonest commands may be entered by using the *) (* PC keypad keys. In this case, no carriage return is needed. *) (* *) (* For all of the relative positioning commands PIBLIST automatically *) (* resets the position to 1 if the result of adding the current *) (* position and the increment is negative or zero. For example, *) (* if page 4 is currently displayed then the command "-10p" skips *) (* backwards to the beginning of the file (page 1). *) (* *) (* The "?" and "E" commands are used to display a command menu and exit *) (* from the PIBLIST program respectively. *) (* *) (* ?: A menu is displayed summarizing all of the legal commands. *) (* The paging prompt is reissued at the bottom of the menu. *) (* *) (* E, EX, EXI, or EXIT: The program terminates and returns to *) (* the calling environment. *) (* *) (* Screen positioning commands *) (* ------ ----------- -------- *) (* *) (* These commands all position the viewing window vertically *) (* in terms of "screens". A "screen" is defined to be a *) (* contiguous group of 24 lines. *) (* *) (* Just carriage return: Display the next screen, i.e., display *) (* the group of 24 lines immediately following the current *) (* screen. *) (* S, +, or +S: Display the next screen. Same as just carriage *) (* return. *) (* You can also use the keypad key PgDn. *) (* - or -S: Display the previous screen, i.e., the group of 24 *) (* lines immediately preceding the current screen. *) (* You can also use the keypad key PgUp. *) (* n, +n, nS, or +ns: Skip forwards n screens. *) (* -n or -nS: Skip backwards n screens. *) (* Sn: Skip to absolute screen number n. *) (* *) (* Notes. "0" redisplays the current screen. This could be used, *) (* for example, after a message from the operator or another user *) (* or process, or after displaying the menu. "S0" or "S1" can be *) (* used to skip backwards to the beginning of the file. To view *) (* the last screen on the file (i.e., the last 24 lines), you could *) (* use "S9999" followed by "-". "S9999" skips to the end of the *) (* file, and "-" backs up one screen. *) (* *) (* The Home key (keypad key 7) can also be used to get to the start of *) (* the file, and the End key (keypad key 1) can be used to get to the *) (* end of the file. *) (* *) (* Page positioning commands *) (* ---- ----------- -------- *) (* *) (* These commands all position the viewing window vertically in *) (* terms of "pages". For FORTRAN line printer carriage control files *) (* (/LPC) a new page is indicated by a line with a "1" in column 1. *) (* For non-line printer carriage control files (/FF) a new page is *) (* indicated by a line with a form feed in column 1. *) (* *) (* The relative page positioning commands all specify page *) (* numbers relative to the "current page number". This is *) (* defined to be the page number of the line currently displayed *) (* at the top of the viewing window. The current page number is *) (* denoted by "x" in the descriptions below. *) (* *) (* P or +P: Skip to the top of the next page, i.e., display the *) (* 24 lines starting with the first line of page x+1. *) (* Ctrl-PgDn: Same as P. *) (* *) (* -P: Skip backwards one page, i.e., display the 24 lines *) (* starting with the first line of page x-1. *) (* Ctrl-PgUp: Same as -P. *) (* *) (* nP or +nP: Skip forwards n pages, i.e., display the 24 lines *) (* starting with the first line of page x+n. *) (* -nP: Skip backwards n pages, i.e., display the 24 lines *) (* starting with the first line of page x-n. *) (* Pn: Skip to absolute page number n, i.e, display the 24 *) (* lines starting with the first line of page n. *) (* *) (* Notes. "0P" skips to the top of the current page. This is *) (* usually not the same as redisplaying the current screen. *) (* For example, "P9999" followed by "0P" skips to the last *) (* page on the file. "P9999" skips to the end of the file, *) (* and "0P" skips to the top of the current page, which is *) (* the last page. If "-1P" were used instead of "0P" in this *) (* example then the second-to-last page would be displayed. *) (* "P0" or "P1" can be used to skip backwards to the beginning *) (* of the file. *) (* *) (* Line positioning commands *) (* ---- ----------- -------- *) (* *) (* These commands all position the viewing window vertically *) (* in terms of lines. PIBLIST numbers the lines of text on the *) (* file sequentially beginning with line number 1. In the *) (* descriptions below "x" denotes the line number of the line *) (* currently displayed at the top of the viewing window. *) (* *) (* L or +L: Skip forwards one line, i.e., display the 24 lines *) (* starting with line number x+1. This effectively scrolls *) (* the window down one line (or, if you prefer, scrolls the *) (* text up one line). *) (* You can also use the down-arrow key (keypad key 2). *) (* -L: Skip backwards one line, i.e., display the 24 lines *) (* starting with line number x-1. This effectively scrolls *) (* the window up one line (or, if you prefer, scrolls the *) (* text down one line). *) (* You can also use the up-arrow key (keypad key 8). *) (* nL or +nL: Skip forwards n lines, i.e., display the 24 lines *) (* starting with line number x+n. *) (* -nL: Skip backwards n lines, i.e., display the 24 lines *) (* starting with line number x-n. *) (* Ln: Skip to absolute line number n, i.e., display the 24 lines *) (* starting with line number n. *) (* *) (* Notes. The relative line positioning commands can be used with *) (* a small forwards or backwards skip count to "slide" the viewing *) (* window a "little bit" forwards or backward, to exactly position *) (* the viewing window with respect to some item of interest. For *) (* example, suppose a table appears on the current screen, starting *) (* at the fourth line of the screen. The command "3L" would slide *) (* the window forwards 3 lines, so that the first line of the table *) (* is at the top of the screen. "L0" or "L1" may be used to skip *) (* backwards to the beginning of the file. *) (* *) (* Column positioning commmands *) (* ------ ----------- --------- *) (* *) (* The three command groups described above are all used to position *) (* the viewing window vertically within the file. The remaining *) (* two groups are used to position the window horizontally within *) (* the file. *) (* *) (* The column positioning commands are used to move the viewing window *) (* left or right across the file. The same set of lines is redisplayed *) (* after the command is entered, with the new setting for the left *) (* column. *) (* *) (* C or +C: Move the window right one column. *) (* -C: Move the window left one column. *) (* nC or +nC: Move the window right n columns. *) (* -nC: Move the window left n columns. *) (* Cn: Reset the leftmost window column to be column n, i.e., move *) (* the window to column n. *) (* Pressing the right arrow (keypad key 6) moves the window right 10 *) (* columns. *) (* Pressing the left arrow (keypad key 4) moves the window left 10 *) (* columns. *) (* *) (* Width setting commands *) (* ----- ------- -------- *) (* *) (* These commands reset the width of the viewing window, i.e., the *) (* number of columns displayed across the screen for each line. *) (* *) (* W or +W: Increment the width by one column. *) (* -W: Decrement the width by one column. *) (* nW or +nW: Increment the width by n columns. *) (* -nW: Decrement the width by n columns. *) (* Wn: Set the width to n columns. *) (* *) (* Note: If you set the width to something larger than 80, lines will *) (* wrap and the screen display will be wrong, unless you have *) (* some kind of special display adapter that allows more than *) (* 80 columns. *) (* *) (* File formats *) (* ---- ------- *) (* *) (* Line printer carriage control (/LPC). These files use column 1 for *) (* special line printer carriage control characters. In particular, *) (* a "1" in column 1 signals the first line of a new page. This *) (* column is always displayed by PIBLIST as the first column of the *) (* viewing window, even if the first display column has been set *) (* to some column greater than 1. For example, if a C5 command *) (* is used and your window width is 80 columns, then PIBLIST would *) (* display columns 1 and 5 through 83 of each line. *) (* *) (* Form feed carriage control (/FF). These files do not use column 1 *) (* for anything special - column 1 simply contains the first regular *) (* text character for each line. A form feed in column 1 signals *) (* the first line of a new page. PIBLIST displays form feeds as <FF>. *) (* The first column is displayed only if the first display column *) (* is set to 1. For example, C5 and W80 would result in columns *) (* 5 through 84 being displayed. *) (* *) (* (* *) (* Initial settings *) (* ------- -------- *) (* *) (* PIBLIST begins by reading the first 'max-buf-lines' lines into *) (* an internal buffer. It then displays the first 24 lines on *) (* the file. Appropriate settings for the first display column *) (* and the window width are chosen by examining these first buffered *) (* lines. 'max-buf-lines' is currently set to 100. *) (* *) (* The initial setting for the window width is 80 columns. *) (* If none one of the first buffered lines *) (* on the file exceed this width then the first display column is *) (* set to column 1. If at least one of the first buffered lines does *) (* extend beyond the width setting then PIBLIST attempts to choose the *) (* smallest value for the first display column such that each line *) (* fits in the window. This is done only if no characters other than *) (* spaces, form feeds, or printer carriage control character (if the *) (* file has them) are lost. For example, suppose you are viewing a *) (* text-formatter output file with one column of carriage control, *) (* seven blank columns for the left margin, and 75 columns of text. *) (* PIBLIST would automatically initialize the first display column to *) (* column 5, so that each line fits in the window. The columns *) (* displayed would be column 1 (the printer carriage control character) *) (* and columns 5 through 83 (the last text column). Columns 2, 3, and *) (* 4 are blank columns and are not displayed. *) (* *) (* In all cases PIBLIST trims trailing blanks from lines before *) (* computing the length. If /T appears on the PIBLIST control *) (* statement then embedded tab characters are also expanded into the *) (* proper number of blanks (1 to 8) before the line length computation *) (* is performed. *) (* *) (* PIBLIST clears the screen on exit. *) (* *) (* *) (* Other notes *) (* ----- ----- *) (* *) (* When the end of the file is reached PIBLIST displays the extra *) (* line "<End of file>". If a vertical positioning command *) (* is used that tries to skip forwards past the end of the *) (* file then this message is all that is displayed. *) (* *) (* PIBLIST maintains an internal buffer of contiguous text lines. *) (* The buffer usually contains either 'max-buf-lines' lines or *) (* 'max-buf-pages of text, whichever is smaller. Currently, *) (* 'max-buf-lines' is 100, and 'max-buf-pages' is 5. The viewing *) (* window of 24 lines is always contained in the buffer, usually *) (* at the end. Vertical positioning commands that skip to a line *) (* currently in the buffer are very fast. For this reason *) (* backwards skips of up to 4 or 5 pages are usually very fast. *) (* For longer backwards skips PIBLIST rewinds the file and skips *) (* forwards to find the requested line. This can take a long *) (* time if the file is large and the requested line is not near *) (* the beginning of the file. *) (* *) (* Unprintable characters are displayed by PIBLIST as <XXX>, where *) (* "XXX" is the ASCII mnemonic for the character. *) (* *) (* If the file to be listed is empty PIBLIST issues an error message *) (* and aborts. *) (* *) (*---------------------------------------------------------------------------*) (* *) (* The text buffer *) (* --------------- *) (* *) (* PIBLIST uses a text line buffer to help make short backwards *) (* skips more efficient. *) (* *) (* The buffer is organized as a circular linked list of lines. *) (* Each line in the list contains a pointer to the next line, *) (* the line number and page number of the line, the length of *) (* the line, and the text of the line. The buffer records are *) (* allocated and linked together at initialization. The lines *) (* are never deallocated, and the links are never changed after *) (* they have been initialized. *) (* *) (* At any point in the program the buffer may contain anywhere *) (* from 0 to max-buf-lines contiguous lines of text from the file. The *) (* global variables first and last point to the first and last *) (* lines in the buffer respectively. If the buffer is empty *) (* (a fairly rare occurrence) then last is set to nil and first *) (* points to some arbitrary element of the list. *) (* *) (* All text lines are stored in the buffer with tabs expanded (if /T) *) (* and trailing blanks trimmed. If /H is specified, then the high-order *) (* bit of each character is stripped before before the line is stored in *) (* the buffer. Other unprintable characters, however, are stored as is - *) (* they are not replaced by their ASCII mnemonics until the line is *) (* displayed. *) (* *) (* The viewing window constitutes a subset of the buffer, and may *) (* be located anywhere within the buffer. The global variables *) (* Top and Bot point to the top and bottom of the viewing window *) (* respectively. *) (* *) (* The file being listed is always positioned at the beginning of *) (* the line immediately following the last line in the buffer. *) (* The global variables cur_line and cur_page keep track of the *) (* line and page number of this next line on the file. *) (* *) (* The circular buffer is the only complex data structure used *) (* by PIBLIST. The remaining global variables are (I hope) *) (* self-explanatory. *) (* *) (*---------------------------------------------------------------------------*) (* *) (* Acknowledgements *) (* ---------------- *) (* *) (* PIBLIST is based upon John Norstad's LIST program for VAX/VMS and the *) (* LISTxx programs of Vernon Buerg. *) (* *) (*---------------------------------------------------------------------------*)